Closes #673.

Summary

Migrate the current 0.2.5829 release train from Zig 0.16.0 to the exact tested 0.17.0-dev.813+2153f8143 snapshot, then remove the migration's cold-path regressions without changing retrieval semantics.

This PR:

• pins and verifies Zig 0.17 in the package, benchmark CI, and release workflow;
• keeps transition benchmark CI honest by running the base and head with each revision's declared 0.16/0.17 compiler (base failure no longer becomes a successful "skipped" comparison);
• vendors the 336KB Zig-0.17-compatible nanoregex source with MIT license, exact upstream commit, and parity fixtures;
• replaces the old mcp-zig dependency with the small protocol-neutral JSON helpers actually used by codedb;
• optimizes exact-word deduplication, Tier-0 document aggregation, release startup/argv, word-index lock lifetime, worker directory reuse, and rolling trigram extraction;
• adds differential parity guards for optimized versus defensive posting paths, canonical versus rolling trigram masks, lazy word-index rebuilding, persisted/mmap ordering, and MCP JSON framing/escaping;
• synchronizes build.zig.zon, src/release_info.zig, npm, and CHANGELOG.md at 0.2.5829;
• documents the complete migration, benchmark method, wins, caveats, and remaining bottleneck in docs/zig-0.17-migration.md and the release changelog.

Retrieval behavior / quality

No scoring, ranking, tokenization, parsing, filtering, result-cap, tie-break, or rendering formula changes in this pass.

The fast paths are guarded by invariants and retain the previous behavior as fallback:

• pair-sorted exact-word postings compact adjacent duplicates linearly; any ordering break reruns full hash deduplication and preserves first-occurrence order;
• nondecreasing Tier-0 postings aggregate contiguous document runs without a map; fragmented/nonmonotonic postings use the previous slots/hash path;
• rolling trigram extraction is compared trigram-by-trigram and path-by-path against canonical extraction, including loc_mask and next_mask;
• direct A/B query hit counts match the Zig 0.16 baseline;
• grouped and semantically equivalent fragmented Tier-0 lists produce identical ordered paths, line numbers/text, scores, and truncation.

Red → green evidence

Before

The compatibility repro under the pinned Zig 0.17 snapshot was zig build test; the pre-migration tree failed on removed build APIs, repetition syntax, bufPrintZ, direct I/O-vtable access, unsupported wasm64 atomics, and incompatible dependency build/source code.

After the tree compiled, the initial same-machine performance A/B was still a regression:

• direct initial indexing, 15 alternating runs on a stable 693-file corpus: Zig 0.16 median 187ms, initial Zig 0.17 median 188ms;
• cold in-process CLI search with isolated HOME, daemon off, telemetry off: Zig 0.16 114.3 ± 2.2ms, initial Zig 0.17 116.4 ± 3.3ms;
• --version: approximately 3% slower.

After

Final immutable-corpus A/B:

• cold single-token CLI: 127.0 ± 26.0ms → 105.7 ± 10.7ms (1.20×, −16.8%);
• warm snapshot CLI: 117.2 ± 27.8ms → 102.8 ± 13.3ms (1.14×, −12.3%);
• exact-word query geometric mean: 3.217× faster;
• all direct queries geometric mean: 1.405× faster;
• search-only geometric mean: 1.007×; symbol geometric mean: 1.013×;
• all direct query hit counts identical.

The known remaining gap is generic full parse/serial-commit initial scan: 166ms → 169ms median (1.8% slower). Production cold single-token search uses the optimized trigram scan path and is materially faster. Closing generic scan needs a larger parser/commit ownership redesign and is intentionally not mixed into this behavior-preserving release.

Benchmark methodology

• Layer: native direct query/index microbenchmarks plus end-to-end CLI process latency.
• Machine: Apple Mac Studio Mac15,14, Apple M3 Ultra, arm64, macOS 26.5.1 (25F80).
• Build: native ReleaseFast for both revisions.
• Baseline: clean 428d8df, Zig 0.16.0.
• Candidate: this branch, Zig 0.17.0-dev.813+2153f8143.
• Corpus: immutable 631-file git archive of 428d8df, stored outside the working repository.
• Direct runs: 20 alternating A/B pairs, 200 iterations per query; reported direct values are medians/geometric means.
• CLI runs: Hyperfine, 5 warmups, 40 measured runs, separate isolated homes/caches, CODEDB_ALLOW_TEMP=1, CODEDB_NO_CLI_DAEMON=1, CODEDB_NO_TELEMETRY=1.
• Cache state: cold CLI uses fresh isolated cache/home; warm CLI uses a prepared snapshot; direct warm queries run in-process after index construction.
• Hyperfine reported outliers for both CLI samples, so mean ± standard deviation is shown and no single run is presented as representative.

The A/B invocation shape was:

env CODEDB_ALLOW_TEMP=1 CODEDB_NO_CLI_DAEMON=1 CODEDB_NO_TELEMETRY=1 \
  hyperfine --warmup 5 --runs 40 \
  --prepare 'rm -rf "$BASE_HOME" "$CURRENT_HOME"; mkdir -p "$BASE_HOME" "$CURRENT_HOME"' \
  'HOME="$BASE_HOME" "$BASE_BIN" "$CORPUS" search config' \
  'HOME="$CURRENT_HOME" "$CURRENT_BIN" "$CORPUS" search config'

The direct harness alternated baseline/candidate order per pair and asserted hit counts before recording timing. Full tables and methodology are in CHANGELOG.md and docs/zig-0.17-migration.md.

Verification

Final tree:

rm -rf .zig-cache && zig build test --summary all
  23/23 build steps succeeded
  892/896 tests passed; 4 platform skips

zig build test-index test-explore test-search --summary all
  index 181/181
  explore 132/132
  search 113/113

zig build test-mcp --summary all
  152/156 passed; 4 platform skips

zig build -Doptimize=ReleaseFast
zig build wasm
python3 scripts/e2e_mcp_test.py --binary zig-out/bin/codedb --project "$PWD"
  20/20 passed

cd vendor/nanoregex
zig build test-all --summary all
  405/405 passed
zig build parity
  27 passed, 0 failed, 0 skipped

git diff --check
  clean

Modified Zig files pass zig fmt/the configured codedb-pro lint. npm/package.json parses as valid JSON. The benchmark workflow parses as YAML, validates the declared base/head compiler selection, verifies both downloaded archives by SHA-256, and fails closed when base benchmarking/comparison fails.

Files / subsystems

• build/release/CI: build.zig, build.zig.zon, .github/workflows/*
• platform/runtime compatibility: src/cio.zig, main/CLI/server/MCP/telemetry/snapshot/WASM modules
• retrieval/performance: src/index.zig, src/explore.zig, src/watcher.zig
• protocol dependency replacement: src/mcp_json.zig
• parity/regression coverage: index/explore/search/MCP and neighboring suites
• vendored dependency: vendor/nanoregex/
• release docs/version surfaces: changelog, migration guide, README, npm, release info

Scope and repository hygiene

This exceeds the default 500-line recommendation because the compiler migration must update the build graph and every compiled target atomically, and the 336KB vendored dependency contributes most of the added lines. Splitting the dependency or compatibility edits would leave intermediate commits unable to build under the release compiler; the performance changes are included because the standing release requirement was to beat, not regress from, Zig 0.16 while preserving 1:1 retrieval.

• Branch was created directly from current origin/release/0.2.5829 at 428d8df (0 commits divergent at creation). It was not rebased onto main because this repository's PR guard requires the active release/* base.
• Generated .zig-cache, .zig-global-cache, zig-out, WASM output, vendor caches, Graff/harness state, and JSONL traces are not committed.
• No generated binary artifacts are included.
• build.zig.zon changes intentionally replace remote dependencies with reproducible local sources; there is no unrelated lockfile churn.
• Benchmark CI and release workflow changed; the benchmark implementation/data format did not.
• The persisted trigram files remain individually tmp+rename replaced; pair publication was already non-transactional in the base and is now documented accurately. This PR writes/flushed both temporaries before either rename but does not claim a transactional pair publication.

Remaining non-blocking risk

Optimized native builds now use the process default stack for the measured ~190KB main frame; Debug retains the 64MB worker trampoline. Mainstream native stacks have ample headroom, but Windows ReleaseFast/ReleaseSmall smoke coverage remains a useful follow-up for constrained targets.

Contribution confirmation

This submission is issue-linked, targets the active release branch, includes before/after evidence and neighboring non-regression checks, discloses the benchmark environment/cache state/run count/aggregation, excludes generated artifacts, explains the unavoidable large scope, and follows CONTRIBUTING.md.